---
title: "`kastrax dev` Reference | Local Development | Kastrax CLI"
description: Documentation for the kastrax dev command, which starts a development server for agents, tools, and workflows.
---

# `kastrax dev` Reference ✅

The `kastrax dev` command starts a development server that exposes REST routes for your agents, tools, and workflows,

## Parameters ✅

<PropertiesTable
  content={[
    {
      name: "--dir",
      type: "string",
      description:
        "Specifies the path to your Kastrax folder (containing agents, tools, and workflows). Defaults to the current working directory.",
      isOptional: true,
    },
    {
      name: "--tools",
      type: "string",
      description:
        "Comma-separated paths to additional tool directories that should be registered. For example: 'src/tools/dbTools,src/tools/scraperTools'.",
      isOptional: true,
    },
  ]}
/>

## Routes ✅

Starting the server with `kastrax dev` exposes a set of REST routes by default:

### System Routes
- **GET `/api`**: Get API status.

### Agent Routes

Agents are expected to be exported from `src/kastrax/agents`.

- **GET `/api/agents`**: Lists the registered agents found in your Kastrax folder.
- **GET `/api/agents/:agentId`**: Get agent by ID.
- **GET `/api/agents/:agentId/evals/ci`**: Get CI evals by agent ID.
- **GET `/api/agents/:agentId/evals/live`**: Get live evals by agent ID.
- **POST `/api/agents/:agentId/generate`**: Sends a text-based prompt to the specified agent, returning the agent's response.
- **POST `/api/agents/:agentId/stream`**: Stream a response from an agent.
- **POST `/api/agents/:agentId/instructions`**: Update an agent's instructions.
- **POST `/api/agents/:agentId/instructions/enhance`**: Generate an improved system prompt from instructions.
- **GET `/api/agents/:agentId/speakers`**: Get available speakers for an agent.
- **POST `/api/agents/:agentId/speak`**: Convert text to speech using the agent's voice provider.
- **POST `/api/agents/:agentId/listen`**: Convert speech to text using the agent's voice provider.
- **POST `/api/agents/:agentId/tools/:toolId/execute`**: Execute a tool through an agent.

### Tool Routes

Tools are expected to be exported from `src/kastrax/tools` (or the configured tools directory).

- **GET `/api/tools`**: Get all tools.
- **GET `/api/tools/:toolId`**: Get tool by ID.
- **POST `/api/tools/:toolId/execute`**: Invokes a specific tool by name, passing input data in the request body.

### Workflow Routes

Workflows are expected to be exported from `src/kastrax/workflows` (or the configured workflows directory).

- **GET `/api/workflows`**: Get all workflows.
- **GET `/api/workflows/:workflowId`**: Get workflow by ID.
- **POST `/api/workflows/:workflowName/start`**: Starts the specified workflow.
- **POST `/api/workflows/:workflowName/:instanceId/event`**: Sends an event or trigger signal to an existing workflow instance.
- **GET `/api/workflows/:workflowName/:instanceId/status`**: Returns status info for a running workflow instance.
- **POST `/api/workflows/:workflowId/resume`**: Resume a suspended workflow step.
- **POST `/api/workflows/:workflowId/resume-async`**: Resume a suspended workflow step asynchronously.
- **POST `/api/workflows/:workflowId/createRun`**: Create a new workflow run.
- **POST `/api/workflows/:workflowId/start-async`**: Execute/Start a workflow asynchronously.
- **GET `/api/workflows/:workflowId/watch`**: Watch workflow transitions in real-time.

### Memory Routes
- **GET `/api/memory/status`**: Get memory status.
- **GET `/api/memory/threads`**: Get all threads.
- **GET `/api/memory/threads/:threadId`**: Get thread by ID.
- **GET `/api/memory/threads/:threadId/messages`**: Get messages for a thread.
- **POST `/api/memory/threads`**: Create a new thread.
- **PATCH `/api/memory/threads/:threadId`**: Update a thread.
- **DELETE `/api/memory/threads/:threadId`**: Delete a thread.
- **POST `/api/memory/save-messages`**: Save messages.

### Telemetry Routes
- **GET `/api/telemetry`**: Get all traces.

### Log Routes
- **GET `/api/logs`**: Get all logs.
- **GET `/api/logs/transports`**: List of all log transports.
- **GET `/api/logs/:runId`**: Get logs by run ID.

### Vector Routes
- **POST `/api/vector/:vectorName/upsert`**: Upsert vectors into an index.
- **POST `/api/vector/:vectorName/create-index`**: Create a new vector index.
- **POST `/api/vector/:vectorName/query`**: Query vectors from an index.
- **GET `/api/vector/:vectorName/indexes`**: List all indexes for a vector store.
- **GET `/api/vector/:vectorName/indexes/:indexName`**: Get details about a specific index.
- **DELETE `/api/vector/:vectorName/indexes/:indexName`**: Delete a specific index.

### OpenAPI Specification

- **GET `/openapi.json`**: Returns an auto-generated OpenAPI specification for your project's routes.
- **GET `/swagger-ui`**: Access Swagger UI for API documentation.

## Additional Notes ✅

The port defaults to 4111. Both the port and hostname can be configured via the kastrax server config. See [Launch Development Server](/docs/local-dev/kastrax-dev#launch-development-server) for configuration details.

Make sure you have your environment variables set up in your `.env.development` or `.env` file for any providers you use (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.).

### Example request

To test an agent after running `kastrax dev`:

```bash
curl -X POST http://localhost:4111/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello, how can you assist me today?" }
    ]
  }'
```
